Autogenerated HTML docs for v1.4.4.2-g1d77
diff --git a/config.txt b/config.txt index f5a552e..a3587f8 100644 --- a/config.txt +++ b/config.txt
@@ -137,10 +137,6 @@ this option, `git pull` defaults to merge the first refspec fetched. Specify multiple values to get an octopus merge. -color.pager:: - A boolean to enable/disable colored output when the pager is in - use (default is true). - color.diff:: When true (or `always`), always use colors in patch. When false (or `never`), never. When set to `auto`, use @@ -157,6 +153,24 @@ `red`, `green`, `yellow`, `blue`, `magenta`, `cyan`, or `white`. +color.pager:: + A boolean to enable/disable colored output when the pager is in + use (default is true). + +color.status:: + A boolean to enable/disable color in the output of + gitlink:git-status[1]. May be set to `true` (or `always`), + `false` (or `never`) or `auto`, in which case colors are used + only when the output is to a terminal. Defaults to false. + +color.status.<slot>:: + Use customized color for status colorization. `<slot>` is + one of `header` (the header text of the status message), + `updated` (files which are updated but not committed), + `changed` (files which are changed but not updated in the index), + or `untracked` (files which are not tracked by git). The values of + these variables may be specified as in color.diff.<slot>. + diff.renameLimit:: The number of files to consider when performing the copy/rename detection; equivalent to the git diff option '-l'. @@ -271,20 +285,6 @@ The default set of branches for gitlink:git-show-branch[1]. See gitlink:git-show-branch[1]. -color.status:: - A boolean to enable/disable color in the output of - gitlink:git-status[1]. May be set to `true` (or `always`), - `false` (or `never`) or `auto`, in which case colors are used - only when the output is to a terminal. Defaults to false. - -color.status.<slot>:: - Use customized color for status colorization. `<slot>` is - one of `header` (the header text of the status message), - `updated` (files which are updated but not committed), - `changed` (files which are changed but not updated in the index), - or `untracked` (files which are not tracked by git). The values of - these variables may be specified as in color.diff.<slot>. - tar.umask:: By default, gitlink:git-tar-tree[1] sets file and directories modes to 0666 or 0777. While this is both useful and acceptable for projects
diff --git a/git-add.html b/git-add.html index 54254fa..b438765 100644 --- a/git-add.html +++ b/git-add.html
@@ -266,7 +266,7 @@ <h2>NAME</h2> <div class="sectionbody"> <p>git-add - - Add files to the index file + Add file contents to the changeset to be committed next </p> </div> </div> @@ -276,10 +276,21 @@ </div> <h2>DESCRIPTION</h2> <div class="sectionbody"> -<p>A simple wrapper for git-update-index to add files to the index, -for people used to do "cvs add".</p> -<p>It only adds non-ignored files, to add ignored files use +<p>All the changed file contents to be committed together in a single set +of changes must be "added" with the <em>add</em> command before using the +<em>commit</em> command. This is not only for adding new files. Even modified +files must be added to the set of changes about to be committed.</p> +<p>This command can be performed multiple times before a commit. The added +content corresponds to the state of specified file(s) at the time the +<em>add</em> command is used. This means the <em>commit</em> command will not consider +subsequent changes to already added content if it is not added again before +the commit.</p> +<p>The <em>git status</em> command can be used to obtain a summary of what is included +for the next commit.</p> +<p>This command only adds non-ignored files, to add ignored files use "git update-index --add".</p> +<p>Please see <a href="git-commit.html">git-commit(1)</a> for alternative ways to add content to a +commit.</p> </div> <h2>OPTIONS</h2> <div class="sectionbody"> @@ -289,7 +300,7 @@ </dt> <dd> <p> - Files to add to the index (see <a href="git-ls-files.html">git-ls-files(1)</a>). + Files to add content from. </p> </dd> <dt> @@ -320,27 +331,6 @@ </dd> </dl> </div> -<h2>DISCUSSION</h2> -<div class="sectionbody"> -<p>The list of <file> given to the command is fed to <tt>git-ls-files</tt> -command to list files that are not registered in the index and -are not ignored/excluded by <tt>$GIT_DIR/info/exclude</tt> file or -<tt>.gitignore</tt> file in each directory. This means two things:</p> -<ol> -<li> -<p> -You can put the name of a directory on the command line, and - the command will add all files in it and its subdirectories; -</p> -</li> -<li> -<p> -Giving the name of a file that is already in index does not - run <tt>git-update-index</tt> on that path. -</p> -</li> -</ol> -</div> <h2>EXAMPLES</h2> <div class="sectionbody"> <dl> @@ -349,8 +339,8 @@ </dt> <dd> <p> - Adds all <tt>*.txt</tt> files that are not in the index under - <tt>Documentation</tt> directory and its subdirectories. + Adds content from all <tt>*.txt</tt> files under <tt>Documentation</tt> + directory and its subdirectories. </p> <p>Note that the asterisk <tt>*</tt> is quoted from the shell in this example; this lets the command to include the files from @@ -361,18 +351,21 @@ </dt> <dd> <p> - Adds all git-*.sh scripts that are not in the index. + Considers adding content from all git-*.sh scripts. Because this example lets shell expand the asterisk (i.e. you are listing the files explicitly), it does not - add <tt>subdir/git-foo.sh</tt> to the index. + consider <tt>subdir/git-foo.sh</tt>. </p> </dd> </dl> </div> <h2>See Also</h2> <div class="sectionbody"> -<p><a href="git-rm.html">git-rm(1)</a> -<a href="git-ls-files.html">git-ls-files(1)</a></p> +<p><a href="git-status.html">git-status(1)</a> +<a href="git-rm.html">git-rm(1)</a> +<a href="git-mv.html">git-mv(1)</a> +<a href="git-commit.html">git-commit(1)</a> +<a href="git-update-index.html">git-update-index(1)</a></p> </div> <h2>Author</h2> <div class="sectionbody"> @@ -388,7 +381,7 @@ </div> <div id="footer"> <div id="footer-text"> -Last updated 03-Oct-2006 08:40:49 UTC +Last updated 13-Dec-2006 21:32:04 UTC </div> </div> </body>
diff --git a/git-add.txt b/git-add.txt index 6342ea3..d86c0e7 100644 --- a/git-add.txt +++ b/git-add.txt
@@ -3,7 +3,7 @@ NAME ---- -git-add - Add files to the index file +git-add - Add file contents to the changeset to be committed next SYNOPSIS -------- @@ -11,16 +11,31 @@ DESCRIPTION ----------- -A simple wrapper for git-update-index to add files to the index, -for people used to do "cvs add". +All the changed file contents to be committed together in a single set +of changes must be "added" with the 'add' command before using the +'commit' command. This is not only for adding new files. Even modified +files must be added to the set of changes about to be committed. -It only adds non-ignored files, to add ignored files use +This command can be performed multiple times before a commit. The added +content corresponds to the state of specified file(s) at the time the +'add' command is used. This means the 'commit' command will not consider +subsequent changes to already added content if it is not added again before +the commit. + +The 'git status' command can be used to obtain a summary of what is included +for the next commit. + +This command only adds non-ignored files, to add ignored files use "git update-index --add". +Please see gitlink:git-commit[1] for alternative ways to add content to a +commit. + + OPTIONS ------- <file>...:: - Files to add to the index (see gitlink:git-ls-files[1]). + Files to add content from. -n:: Don't actually add the file(s), just show if they exist. @@ -34,27 +49,12 @@ for command-line options). -DISCUSSION ----------- - -The list of <file> given to the command is fed to `git-ls-files` -command to list files that are not registered in the index and -are not ignored/excluded by `$GIT_DIR/info/exclude` file or -`.gitignore` file in each directory. This means two things: - -. You can put the name of a directory on the command line, and - the command will add all files in it and its subdirectories; - -. Giving the name of a file that is already in index does not - run `git-update-index` on that path. - - EXAMPLES -------- git-add Documentation/\\*.txt:: - Adds all `\*.txt` files that are not in the index under - `Documentation` directory and its subdirectories. + Adds content from all `\*.txt` files under `Documentation` + directory and its subdirectories. + Note that the asterisk `\*` is quoted from the shell in this example; this lets the command to include the files from @@ -62,15 +62,18 @@ git-add git-*.sh:: - Adds all git-*.sh scripts that are not in the index. + Considers adding content from all git-*.sh scripts. Because this example lets shell expand the asterisk (i.e. you are listing the files explicitly), it does not - add `subdir/git-foo.sh` to the index. + consider `subdir/git-foo.sh`. See Also -------- +gitlink:git-status[1] gitlink:git-rm[1] -gitlink:git-ls-files[1] +gitlink:git-mv[1] +gitlink:git-commit[1] +gitlink:git-update-index[1] Author ------
diff --git a/git-branch.html b/git-branch.html index 4867789..74a4e26 100644 --- a/git-branch.html +++ b/git-branch.html
@@ -273,8 +273,9 @@ <h2>SYNOPSIS</h2> <div class="sectionbody"> <div class="verseblock"> -<div class="content"><em>git-branch</em> [-r] [-a] [-v] [--abbrev=<length>] +<div class="content"><em>git-branch</em> [-r | -a] [-v [--abbrev=<length>]] <em>git-branch</em> [-l] [-f] <branchname> [<start-point>] +<em>git-branch</em> (-m | -M) [<oldbranch>] <newbranch> <em>git-branch</em> (-d | -D) <branchname>…</div></div> </div> <h2>DESCRIPTION</h2> @@ -287,6 +288,11 @@ It will start out with a head equal to the one given as <start-point>. If no <start-point> is given, the branch will be created with a head equal to that of the currently checked out branch.</p> +<p>With a <em>-m</em> or <em>-M</em> option, <oldbranch> will be renamed to <newbranch>. +If <oldbranch> had a corresponding reflog, it is renamed to match +<newbranch>, and a reflog entry is created to remember the branch +renaming. If <newbranch> exists, -M must be used to force the rename +to happen.</p> <p>With a <tt>-d</tt> or <tt>-D</tt> option, <tt><branchname></tt> will be deleted. You may specify more than one branch for deletion. If the branch currently has a ref log then the ref log will also be deleted.</p> @@ -329,6 +335,22 @@ </p> </dd> <dt> +-m +</dt> +<dd> +<p> + Move/rename a branch and the corresponding reflog. +</p> +</dd> +<dt> +-M +</dt> +<dd> +<p> + Move/rename a branch even if the new branchname already exists. +</p> +</dd> +<dt> -r </dt> <dd> @@ -349,7 +371,7 @@ </dt> <dd> <p> - Show sha1 and subject message for each head. + Show sha1 and commit subjectline for each head. </p> </dd> <dt> @@ -382,6 +404,23 @@ is omitted, the current branch is assumed. </p> </dd> +<dt> +<oldbranch> +</dt> +<dd> +<p> + The name of an existing branch to rename. +</p> +</dd> +<dt> +<newbranch> +</dt> +<dd> +<p> + The new name for an existing branch. The same restrictions as for + <branchname> applies. +</p> +</dd> </dl> </div> <h2>Examples</h2> @@ -448,7 +487,7 @@ </div> <div id="footer"> <div id="footer-text"> -Last updated 25-Nov-2006 10:05:14 UTC +Last updated 13-Dec-2006 21:32:04 UTC </div> </div> </body>
diff --git a/git-branch.txt b/git-branch.txt index 4f5b5d5..71417fe 100644 --- a/git-branch.txt +++ b/git-branch.txt
@@ -8,8 +8,9 @@ SYNOPSIS -------- [verse] -'git-branch' [-r] [-a] [-v] [--abbrev=<length>] +'git-branch' [-r | -a] [-v [--abbrev=<length>]] 'git-branch' [-l] [-f] <branchname> [<start-point>] +'git-branch' (-m | -M) [<oldbranch>] <newbranch> 'git-branch' (-d | -D) <branchname>... DESCRIPTION @@ -24,6 +25,12 @@ If no <start-point> is given, the branch will be created with a head equal to that of the currently checked out branch. +With a '-m' or '-M' option, <oldbranch> will be renamed to <newbranch>. +If <oldbranch> had a corresponding reflog, it is renamed to match +<newbranch>, and a reflog entry is created to remember the branch +renaming. If <newbranch> exists, -M must be used to force the rename +to happen. + With a `-d` or `-D` option, `<branchname>` will be deleted. You may specify more than one branch for deletion. If the branch currently has a ref log then the ref log will also be deleted. @@ -46,6 +53,12 @@ Force the creation of a new branch even if it means deleting a branch that already exists with the same name. +-m:: + Move/rename a branch and the corresponding reflog. + +-M:: + Move/rename a branch even if the new branchname already exists. + -r:: List the remote-tracking branches. @@ -53,7 +66,7 @@ List both remote-tracking branches and local branches. -v:: - Show sha1 and subject message for each head. + Show sha1 and commit subjectline for each head. --abbrev=<length>:: Alter minimum display length for sha1 in output listing, @@ -70,6 +83,12 @@ be given as a branch name, a commit-id, or a tag. If this option is omitted, the current branch is assumed. +<oldbranch>:: + The name of an existing branch to rename. + +<newbranch>:: + The new name for an existing branch. The same restrictions as for + <branchname> applies. Examples
diff --git a/git-commit.html b/git-commit.html index 8d8a943..b163557 100644 --- a/git-commit.html +++ b/git-commit.html
@@ -279,15 +279,45 @@ </div> <h2>DESCRIPTION</h2> <div class="sectionbody"> -<p>Updates the index file for given paths, or all modified files if -<em>-a</em> is specified, and makes a commit object. The command specified -by either the VISUAL or EDITOR environment variables are used to edit -the commit log message.</p> -<p>Several environment variable are used during commits. They are -documented in <a href="git-commit-tree.html">git-commit-tree(1)</a>.</p> -<p>This command can run <tt>commit-msg</tt>, <tt>pre-commit</tt>, and -<tt>post-commit</tt> hooks. See <a href="hooks.html">hooks</a> for more -information.</p> +<p>Use <em>git commit</em> when you want to record your changes into the repository +along with a log message describing what the commit is about. All changes +to be committed must be explicitly identified using one of the following +methods:</p> +<ol> +<li> +<p> +by using <a href="git-add.html">git-add(1)</a> to incrementally "add" changes to the + next commit before using the <em>commit</em> command (Note: even modified + files must be "added"); +</p> +</li> +<li> +<p> +by using <a href="git-rm.html">git-rm(1)</a> to identify content removal for the next + commit, again before using the <em>commit</em> command; +</p> +</li> +<li> +<p> +by directly listing files containing changes to be committed as arguments + to the <em>commit</em> command, in which cases only those files alone will be + considered for the commit; +</p> +</li> +<li> +<p> +by using the -a switch with the <em>commit</em> command to automatically "add" + changes from all known files i.e. files that have already been committed + before, and perform the actual commit. +</p> +</li> +</ol> +<p>The <a href="git-status.html">git-status(1)</a> command can be used to obtain a +summary of what is included by any of the above for the next +commit by giving the same set of parameters you would give to +this command.</p> +<p>If you make a commit and then found a mistake immediately after +that, you can recover from it with <a href="git-reset.html">git-reset(1)</a>.</p> </div> <h2>OPTIONS</h2> <div class="sectionbody"> @@ -297,9 +327,9 @@ </dt> <dd> <p> - Update all paths in the index file. This flag notices - files that have been modified and deleted, but new files - you have not told git about are not affected. + Tell the command to automatically stage files that have + been modified and deleted, but new files you have not + told git about are not affected. </p> </dd> <dt> @@ -349,24 +379,16 @@ </p> </dd> <dt> --v|--verify +--no-verify </dt> <dd> <p> - Look for suspicious lines the commit introduces, and - abort committing if there is one. The definition of - <em>suspicious lines</em> is currently the lines that has - trailing whitespaces, and the lines whose indentation - has a SP character immediately followed by a TAB - character. This is the default. -</p> -</dd> -<dt> --n|--no-verify -</dt> -<dd> -<p> - The opposite of <tt>--verify</tt>. + By default, the command looks for suspicious lines the + commit introduces, and aborts committing if there is one. + The definition of <em>suspicious lines</em> is currently the + lines that has trailing whitespaces, and the lines whose + indentation has a SP character immediately followed by a + TAB character. This option turns off the check. </p> </dd> <dt> @@ -409,21 +431,10 @@ </dt> <dd> <p> - Instead of committing only the files specified on the - command line, update them in the index file and then - commit the whole index. This is the traditional - behavior. -</p> -</dd> -<dt> --o|--only -</dt> -<dd> -<p> - Commit only the files specified on the command line. - This format cannot be used during a merge, nor when the - index and the latest commit does not match on the - specified paths to avoid confusion. + Before making a commit out of staged contents so far, + stage the contents of paths given on the command line + as well. This is usually not what you want unless you + are concluding a conflicted merge. </p> </dd> <dt> @@ -439,62 +450,115 @@ </dt> <dd> <p> - Files to be committed. The meaning of these is - different between <tt>--include</tt> and <tt>--only</tt>. Without - either, it defaults <tt>--only</tt> semantics. + When files are given on the command line, the command + commits the contents of the named files, without + recording the changes already staged. The contents of + these files are also staged for the next commit on top + of what have been staged before. </p> </dd> </dl> -<p>If you make a commit and then found a mistake immediately after -that, you can recover from it with <a href="git-reset.html">git-reset(1)</a>.</p> </div> -<h2>Discussion</h2> +<h2>EXAMPLES</h2> <div class="sectionbody"> -<p><tt>git commit</tt> without _any_ parameter commits the tree structure -recorded by the current index file. This is a whole-tree commit -even the command is invoked from a subdirectory.</p> -<p><tt>git commit --include paths…</tt> is equivalent to</p> -<div class="literalblock"> +<p>When recording your own work, the contents of modified files in +your working tree are temporarily stored to a staging area +called the "index" with <a href="git-add.html">git-add(1)</a>. Removal +of a file is staged with <a href="git-rm.html">git-rm(1)</a>. After building the +state to be committed incrementally with these commands, <tt>git +commit</tt> (without any pathname parameter) is used to record what +has been staged so far. This is the most basic form of the +command. An example:</p> +<div class="listingblock"> <div class="content"> -<pre><tt>git update-index --remove paths... -git commit</tt></pre> +<pre><tt>$ edit hello.c +$ git rm goodbye.c +$ git add hello.c +$ git commit</tt></pre> </div></div> -<p>That is, update the specified paths to the index and then commit -the whole tree.</p> -<p><tt>git commit paths…</tt> largely bypasses the index file and -commits only the changes made to the specified paths. It has -however several safety valves to prevent confusion.</p> -<ol> -<li> -<p> -It refuses to run during a merge (i.e. when - <tt>$GIT_DIR/MERGE_HEAD</tt> exists), and reminds trained git users - that the traditional semantics now needs -i flag. -</p> -</li> -<li> -<p> -It refuses to run if named <tt>paths…</tt> are different in HEAD - and the index (ditto about reminding). Added paths are OK. - This is because an earlier <tt>git diff</tt> (not <tt>git diff HEAD</tt>) - would have shown the differences since the last <tt>git - update-index paths…</tt> to the user, and an inexperienced user - may mistakenly think that the changes between the index and - the HEAD (i.e. earlier changes made before the last <tt>git - update-index paths…</tt> was done) are not being committed. -</p> -</li> -<li> -<p> -It reads HEAD commit into a temporary index file, updates the - specified <tt>paths…</tt> and makes a commit. At the same time, - the real index file is also updated with the same <tt>paths…</tt>. -</p> -</li> -</ol> -<p><tt>git commit --all</tt> updates the index file with _all_ changes to -the working tree, and makes a whole-tree commit, regardless of -which subdirectory the command is invoked in.</p> +<p>Instead of staging files after each individual change, you can +tell <tt>git commit</tt> to notice the changes to the files whose +contents are tracked in +your working tree and do corresponding <tt>git add</tt> and <tt>git rm</tt> +for you. That is, this example does the same as the earlier +example if there is no other change in your working tree:</p> +<div class="listingblock"> +<div class="content"> +<pre><tt>$ edit hello.c +$ rm goodbye.c +$ git commit -a</tt></pre> +</div></div> +<p>The command <tt>git commit -a</tt> first looks at your working tree, +notices that you have modified hello.c and removed goodbye.c, +and performs necessary <tt>git add</tt> and <tt>git rm</tt> for you.</p> +<p>After staging changes to many files, you can alter the order the +changes are recorded in, by giving pathnames to <tt>git commit</tt>. +When pathnames are given, the command makes a commit that +only records the changes made to the named paths:</p> +<div class="listingblock"> +<div class="content"> +<pre><tt>$ edit hello.c hello.h +$ git add hello.c hello.h +$ edit Makefile +$ git commit Makefile</tt></pre> +</div></div> +<p>This makes a commit that records the modification to <tt>Makefile</tt>. +The changes staged for <tt>hello.c</tt> and <tt>hello.h</tt> are not included +in the resulting commit. However, their changes are not lost — +they are still staged and merely held back. After the above +sequence, if you do:</p> +<div class="listingblock"> +<div class="content"> +<pre><tt>$ git commit</tt></pre> +</div></div> +<p>this second commit would record the changes to <tt>hello.c</tt> and +<tt>hello.h</tt> as expected.</p> +<p>After a merge (initiated by either <a href="git-merge.html">git-merge(1)</a> or +<a href="git-pull.html">git-pull(1)</a>) stops because of conflicts, cleanly merged +paths are already staged to be committed for you, and paths that +conflicted are left in unmerged state. You would have to first +check which paths are conflicting with <a href="git-status.html">git-status(1)</a> +and after fixing them manually in your working tree, you would +stage the result as usual with <a href="git-add.html">git-add(1)</a>:</p> +<div class="listingblock"> +<div class="content"> +<pre><tt>$ git status | grep unmerged +unmerged: hello.c +$ edit hello.c +$ git add hello.c</tt></pre> +</div></div> +<p>After resolving conflicts and staging the result, <tt>git ls-files -u</tt> +would stop mentioning the conflicted path. When you are done, +run <tt>git commit</tt> to finally record the merge:</p> +<div class="listingblock"> +<div class="content"> +<pre><tt>$ git commit</tt></pre> +</div></div> +<p>As with the case to record your own changes, you can use <tt>-a</tt> +option to save typing. One difference is that during a merge +resolution, you cannot use <tt>git commit</tt> with pathnames to +alter the order the changes are committed, because the merge +should be recorded as a single commit. In fact, the command +refuses to run when given pathnames (but see <tt>-i</tt> option).</p> +</div> +<h2>ENVIRONMENT VARIABLES</h2> +<div class="sectionbody"> +<p>The command specified by either the VISUAL or EDITOR environment +variables is used to edit the commit log message.</p> +</div> +<h2>HOOKS</h2> +<div class="sectionbody"> +<p>This command can run <tt>commit-msg</tt>, <tt>pre-commit</tt>, and +<tt>post-commit</tt> hooks. See <a href="hooks.html">hooks</a> for more +information.</p> +</div> +<h2>SEE ALSO</h2> +<div class="sectionbody"> +<p><a href="git-add.html">git-add(1)</a>, +<a href="git-rm.html">git-rm(1)</a>, +<a href="git-mv.html">git-mv(1)</a>, +<a href="git-merge.html">git-merge(1)</a>, +<a href="git-commit-tree.html">git-commit-tree(1)</a></p> </div> <h2>Author</h2> <div class="sectionbody"> @@ -507,7 +571,7 @@ </div> <div id="footer"> <div id="footer-text"> -Last updated 03-Oct-2006 08:40:57 UTC +Last updated 13-Dec-2006 21:32:05 UTC </div> </div> </body>
diff --git a/git-commit.txt b/git-commit.txt index 517a86b..97d66ef 100644 --- a/git-commit.txt +++ b/git-commit.txt
@@ -14,25 +14,41 @@ DESCRIPTION ----------- -Updates the index file for given paths, or all modified files if -'-a' is specified, and makes a commit object. The command specified -by either the VISUAL or EDITOR environment variables are used to edit -the commit log message. +Use 'git commit' when you want to record your changes into the repository +along with a log message describing what the commit is about. All changes +to be committed must be explicitly identified using one of the following +methods: -Several environment variable are used during commits. They are -documented in gitlink:git-commit-tree[1]. +1. by using gitlink:git-add[1] to incrementally "add" changes to the + next commit before using the 'commit' command (Note: even modified + files must be "added"); +2. by using gitlink:git-rm[1] to identify content removal for the next + commit, again before using the 'commit' command; -This command can run `commit-msg`, `pre-commit`, and -`post-commit` hooks. See link:hooks.html[hooks] for more -information. +3. by directly listing files containing changes to be committed as arguments + to the 'commit' command, in which cases only those files alone will be + considered for the commit; + +4. by using the -a switch with the 'commit' command to automatically "add" + changes from all known files i.e. files that have already been committed + before, and perform the actual commit. + +The gitlink:git-status[1] command can be used to obtain a +summary of what is included by any of the above for the next +commit by giving the same set of parameters you would give to +this command. + +If you make a commit and then found a mistake immediately after +that, you can recover from it with gitlink:git-reset[1]. + OPTIONS ------- -a|--all:: - Update all paths in the index file. This flag notices - files that have been modified and deleted, but new files - you have not told git about are not affected. + Tell the command to automatically stage files that have + been modified and deleted, but new files you have not + told git about are not affected. -c or -C <commit>:: Take existing commit object, and reuse the log message @@ -55,16 +71,13 @@ -s|--signoff:: Add Signed-off-by line at the end of the commit message. --v|--verify:: - Look for suspicious lines the commit introduces, and - abort committing if there is one. The definition of - 'suspicious lines' is currently the lines that has - trailing whitespaces, and the lines whose indentation - has a SP character immediately followed by a TAB - character. This is the default. - --n|--no-verify:: - The opposite of `--verify`. +--no-verify:: + By default, the command looks for suspicious lines the + commit introduces, and aborts committing if there is one. + The definition of 'suspicious lines' is currently the + lines that has trailing whitespaces, and the lines whose + indentation has a SP character immediately followed by a + TAB character. This option turns off the check. -e|--edit:: The message taken from file with `-F`, command line with @@ -95,69 +108,137 @@ -- -i|--include:: - Instead of committing only the files specified on the - command line, update them in the index file and then - commit the whole index. This is the traditional - behavior. - --o|--only:: - Commit only the files specified on the command line. - This format cannot be used during a merge, nor when the - index and the latest commit does not match on the - specified paths to avoid confusion. + Before making a commit out of staged contents so far, + stage the contents of paths given on the command line + as well. This is usually not what you want unless you + are concluding a conflicted merge. \--:: Do not interpret any more arguments as options. <file>...:: - Files to be committed. The meaning of these is - different between `--include` and `--only`. Without - either, it defaults `--only` semantics. - -If you make a commit and then found a mistake immediately after -that, you can recover from it with gitlink:git-reset[1]. + When files are given on the command line, the command + commits the contents of the named files, without + recording the changes already staged. The contents of + these files are also staged for the next commit on top + of what have been staged before. -Discussion ----------- +EXAMPLES +-------- +When recording your own work, the contents of modified files in +your working tree are temporarily stored to a staging area +called the "index" with gitlink:git-add[1]. Removal +of a file is staged with gitlink:git-rm[1]. After building the +state to be committed incrementally with these commands, `git +commit` (without any pathname parameter) is used to record what +has been staged so far. This is the most basic form of the +command. An example: -`git commit` without _any_ parameter commits the tree structure -recorded by the current index file. This is a whole-tree commit -even the command is invoked from a subdirectory. +------------ +$ edit hello.c +$ git rm goodbye.c +$ git add hello.c +$ git commit +------------ -`git commit --include paths...` is equivalent to +//////////// +We should fix 'git rm' to remove goodbye.c from both index and +working tree for the above example. +//////////// - git update-index --remove paths... - git commit +Instead of staging files after each individual change, you can +tell `git commit` to notice the changes to the files whose +contents are tracked in +your working tree and do corresponding `git add` and `git rm` +for you. That is, this example does the same as the earlier +example if there is no other change in your working tree: -That is, update the specified paths to the index and then commit -the whole tree. +------------ +$ edit hello.c +$ rm goodbye.c +$ git commit -a +------------ -`git commit paths...` largely bypasses the index file and -commits only the changes made to the specified paths. It has -however several safety valves to prevent confusion. +The command `git commit -a` first looks at your working tree, +notices that you have modified hello.c and removed goodbye.c, +and performs necessary `git add` and `git rm` for you. -. It refuses to run during a merge (i.e. when - `$GIT_DIR/MERGE_HEAD` exists), and reminds trained git users - that the traditional semantics now needs -i flag. +After staging changes to many files, you can alter the order the +changes are recorded in, by giving pathnames to `git commit`. +When pathnames are given, the command makes a commit that +only records the changes made to the named paths: -. It refuses to run if named `paths...` are different in HEAD - and the index (ditto about reminding). Added paths are OK. - This is because an earlier `git diff` (not `git diff HEAD`) - would have shown the differences since the last `git - update-index paths...` to the user, and an inexperienced user - may mistakenly think that the changes between the index and - the HEAD (i.e. earlier changes made before the last `git - update-index paths...` was done) are not being committed. +------------ +$ edit hello.c hello.h +$ git add hello.c hello.h +$ edit Makefile +$ git commit Makefile +------------ -. It reads HEAD commit into a temporary index file, updates the - specified `paths...` and makes a commit. At the same time, - the real index file is also updated with the same `paths...`. +This makes a commit that records the modification to `Makefile`. +The changes staged for `hello.c` and `hello.h` are not included +in the resulting commit. However, their changes are not lost -- +they are still staged and merely held back. After the above +sequence, if you do: -`git commit --all` updates the index file with _all_ changes to -the working tree, and makes a whole-tree commit, regardless of -which subdirectory the command is invoked in. +------------ +$ git commit +------------ +this second commit would record the changes to `hello.c` and +`hello.h` as expected. + +After a merge (initiated by either gitlink:git-merge[1] or +gitlink:git-pull[1]) stops because of conflicts, cleanly merged +paths are already staged to be committed for you, and paths that +conflicted are left in unmerged state. You would have to first +check which paths are conflicting with gitlink:git-status[1] +and after fixing them manually in your working tree, you would +stage the result as usual with gitlink:git-add[1]: + +------------ +$ git status | grep unmerged +unmerged: hello.c +$ edit hello.c +$ git add hello.c +------------ + +After resolving conflicts and staging the result, `git ls-files -u` +would stop mentioning the conflicted path. When you are done, +run `git commit` to finally record the merge: + +------------ +$ git commit +------------ + +As with the case to record your own changes, you can use `-a` +option to save typing. One difference is that during a merge +resolution, you cannot use `git commit` with pathnames to +alter the order the changes are committed, because the merge +should be recorded as a single commit. In fact, the command +refuses to run when given pathnames (but see `-i` option). + + +ENVIRONMENT VARIABLES +--------------------- +The command specified by either the VISUAL or EDITOR environment +variables is used to edit the commit log message. + +HOOKS +----- +This command can run `commit-msg`, `pre-commit`, and +`post-commit` hooks. See link:hooks.html[hooks] for more +information. + + +SEE ALSO +-------- +gitlink:git-add[1], +gitlink:git-rm[1], +gitlink:git-mv[1], +gitlink:git-merge[1], +gitlink:git-commit-tree[1] Author ------
diff --git a/git-merge-index.html b/git-merge-index.html index 91fedf0..e7eeeaf 100644 --- a/git-merge-index.html +++ b/git-merge-index.html
@@ -325,8 +325,8 @@ <p>If "git-merge-index" is called with multiple <file>s (or -a) then it processes them in turn only stopping if merge returns a non-zero exit code.</p> -<p>Typically this is run with the a script calling the merge command from -the RCS package.</p> +<p>Typically this is run with the a script calling git's imitation of +the merge command from the RCS package.</p> <p>A sample script called "git-merge-one-file" is included in the distribution.</p> <p>ALERT ALERT ALERT! The git "merge object order" is different from the @@ -372,7 +372,7 @@ </div> <div id="footer"> <div id="footer-text"> -Last updated 03-Oct-2006 08:41:12 UTC +Last updated 13-Dec-2006 21:32:05 UTC </div> </div> </body>
diff --git a/git-merge-index.txt b/git-merge-index.txt index 6cd0601..0cf505e 100644 --- a/git-merge-index.txt +++ b/git-merge-index.txt
@@ -40,8 +40,8 @@ processes them in turn only stopping if merge returns a non-zero exit code. -Typically this is run with the a script calling the merge command from -the RCS package. +Typically this is run with the a script calling git's imitation of +the merge command from the RCS package. A sample script called "git-merge-one-file" is included in the distribution.
diff --git a/git-read-tree.html b/git-read-tree.html index bc765ea..1bdc827 100644 --- a/git-read-tree.html +++ b/git-read-tree.html
@@ -272,7 +272,7 @@ </div> <h2>SYNOPSIS</h2> <div class="sectionbody"> -<p><em>git-read-tree</em> (<tree-ish> | [[-m [--aggressive] | --reset | --prefix=<prefix>] [-u | -i]] <tree-ish1> [<tree-ish2> [<tree-ish3>]])</p> +<p><em>git-read-tree</em> (<tree-ish> | [[-m [--aggressive] | --reset | --prefix=<prefix>] [-u | -i]] [--exclude-per-directory=<gitignore>] <tree-ish1> [<tree-ish2> [<tree-ish3>]])</p> </div> <h2>DESCRIPTION</h2> <div class="sectionbody"> @@ -377,6 +377,26 @@ </p> </dd> <dt> +--exclude-per-directory=<gitignore> +</dt> +<dd> +<p> + When running the command with <tt>-u</tt> and <tt>-m</tt> options, the + merge result may need to overwrite paths that are not + tracked in the current branch. The command usually + refuses to proceed with the merge to avoid losing such a + path. However this safety valve sometimes gets in the + way. For example, it often happens that the other + branch added a file that used to be a generated file in + your branch, and the safety valve triggers when you try + to switch to that branch after you ran <tt>make</tt> but before + running <tt>make clean</tt> to remove the generated file. This + option tells the command to read per-directory exclude + file (usually <em>.gitignore</em>) and allows such an untracked + but explicitly ignored file to be overwritten. +</p> +</dd> +<dt> <tree-ish#> </dt> <dd> @@ -662,7 +682,7 @@ </div> <div id="footer"> <div id="footer-text"> -Last updated 03-Oct-2006 08:41:20 UTC +Last updated 13-Dec-2006 21:32:06 UTC </div> </div> </body>
diff --git a/git-read-tree.txt b/git-read-tree.txt index 11bd9c0..0ff2890 100644 --- a/git-read-tree.txt +++ b/git-read-tree.txt
@@ -8,7 +8,7 @@ SYNOPSIS -------- -'git-read-tree' (<tree-ish> | [[-m [--aggressive] | --reset | --prefix=<prefix>] [-u | -i]] <tree-ish1> [<tree-ish2> [<tree-ish3>]]) +'git-read-tree' (<tree-ish> | [[-m [--aggressive] | --reset | --prefix=<prefix>] [-u | -i]] [--exclude-per-directory=<gitignore>] <tree-ish1> [<tree-ish2> [<tree-ish3>]]) DESCRIPTION @@ -71,6 +71,20 @@ directory. Note that the `<prefix>/` value must end with a slash. +--exclude-per-directory=<gitignore>:: + When running the command with `-u` and `-m` options, the + merge result may need to overwrite paths that are not + tracked in the current branch. The command usually + refuses to proceed with the merge to avoid losing such a + path. However this safety valve sometimes gets in the + way. For example, it often happens that the other + branch added a file that used to be a generated file in + your branch, and the safety valve triggers when you try + to switch to that branch after you ran `make` but before + running `make clean` to remove the generated file. This + option tells the command to read per-directory exclude + file (usually '.gitignore') and allows such an untracked + but explicitly ignored file to be overwritten. <tree-ish#>:: The id of the tree object(s) to be read/merged.
diff --git a/git-repo-config.html b/git-repo-config.html index 8935bb9..bdeb43e 100644 --- a/git-repo-config.html +++ b/git-repo-config.html
@@ -748,15 +748,6 @@ </p> </dd> <dt> -color.pager -</dt> -<dd> -<p> - A boolean to enable/disable colored output when the pager is in - use (default is true). -</p> -</dd> -<dt> color.diff </dt> <dd> @@ -783,6 +774,39 @@ </p> </dd> <dt> +color.pager +</dt> +<dd> +<p> + A boolean to enable/disable colored output when the pager is in + use (default is true). +</p> +</dd> +<dt> +color.status +</dt> +<dd> +<p> + A boolean to enable/disable color in the output of + <a href="git-status.html">git-status(1)</a>. May be set to <tt>true</tt> (or <tt>always</tt>), + <tt>false</tt> (or <tt>never</tt>) or <tt>auto</tt>, in which case colors are used + only when the output is to a terminal. Defaults to false. +</p> +</dd> +<dt> +color.status.<slot> +</dt> +<dd> +<p> + Use customized color for status colorization. <tt><slot></tt> is + one of <tt>header</tt> (the header text of the status message), + <tt>updated</tt> (files which are updated but not committed), + <tt>changed</tt> (files which are changed but not updated in the index), + or <tt>untracked</tt> (files which are not tracked by git). The values of + these variables may be specified as in color.diff.<slot>. +</p> +</dd> +<dt> diff.renameLimit </dt> <dd> @@ -1022,30 +1046,6 @@ </p> </dd> <dt> -color.status -</dt> -<dd> -<p> - A boolean to enable/disable color in the output of - <a href="git-status.html">git-status(1)</a>. May be set to <tt>true</tt> (or <tt>always</tt>), - <tt>false</tt> (or <tt>never</tt>) or <tt>auto</tt>, in which case colors are used - only when the output is to a terminal. Defaults to false. -</p> -</dd> -<dt> -color.status.<slot> -</dt> -<dd> -<p> - Use customized color for status colorization. <tt><slot></tt> is - one of <tt>header</tt> (the header text of the status message), - <tt>updated</tt> (files which are updated but not committed), - <tt>changed</tt> (files which are changed but not updated in the index), - or <tt>untracked</tt> (files which are not tracked by git). The values of - these variables may be specified as in color.diff.<slot>. -</p> -</dd> -<dt> tar.umask </dt> <dd> @@ -1140,7 +1140,7 @@ </div> <div id="footer"> <div id="footer-text"> -Last updated 13-Dec-2006 10:14:08 UTC +Last updated 13-Dec-2006 21:32:06 UTC </div> </div> </body>
diff --git a/git-rerere.html b/git-rerere.html index e311b61..aee0415 100644 --- a/git-rerere.html +++ b/git-rerere.html
@@ -272,7 +272,7 @@ </div> <h2>SYNOPSIS</h2> <div class="sectionbody"> -<p><em>git-rerere</em></p> +<p><em>git-rerere</em> [clear|diff|status]</p> </div> <h2>DESCRIPTION</h2> <div class="sectionbody"> @@ -294,6 +294,53 @@ </tr></table> </div> </div> +<h2>COMMANDS</h2> +<div class="sectionbody"> +<p>Normally, git-rerere is run without arguments or user-intervention. +However, it has several commands that allow it to interact with +its working state.</p> +<dl> +<dt> +<em>clear</em> +</dt> +<dd> +<p> +This resets the metadata used by rerere if a merge resolution is to be +is aborted. Calling <a href="git-am.html">git-am(1)</a> --skip or <a href="git-rebase.html">git-rebase(1)</a> +[--skip|--abort] will automatcally invoke this command. +</p> +</dd> +<dt> +<em>diff</em> +</dt> +<dd> +<p> +This displays diffs for the current state of the resolution. It is +useful for tracking what has changed while the user is resolving +conflicts. Additional arguments are passed directly to the system +diff(1) command installed in PATH. +</p> +</dd> +<dt> +<em>status</em> +</dt> +<dd> +<p> +Like diff, but this only prints the filenames that will be tracked +for resolutions. +</p> +</dd> +<dt> +<em>gc</em> +</dt> +<dd> +<p> +This command is used to prune records of conflicted merge that +occurred long time ago. +</p> +</dd> +</dl> +</div> <h2>DISCUSSION</h2> <div class="sectionbody"> <p>When your topic branch modifies overlapping area that your @@ -431,7 +478,7 @@ </div> <div id="footer"> <div id="footer-text"> -Last updated 03-Oct-2006 08:41:23 UTC +Last updated 13-Dec-2006 21:32:08 UTC </div> </div> </body>
diff --git a/git-rerere.txt b/git-rerere.txt index 8b6b651..116dca4 100644 --- a/git-rerere.txt +++ b/git-rerere.txt
@@ -7,8 +7,7 @@ SYNOPSIS -------- -'git-rerere' - +'git-rerere' [clear|diff|status] DESCRIPTION ----------- @@ -27,6 +26,38 @@ You need to create `$GIT_DIR/rr-cache` directory to enable this command. + +COMMANDS +-------- + +Normally, git-rerere is run without arguments or user-intervention. +However, it has several commands that allow it to interact with +its working state. + +'clear':: + +This resets the metadata used by rerere if a merge resolution is to be +is aborted. Calling gitlink:git-am[1] --skip or gitlink:git-rebase[1] +[--skip|--abort] will automatcally invoke this command. + +'diff':: + +This displays diffs for the current state of the resolution. It is +useful for tracking what has changed while the user is resolving +conflicts. Additional arguments are passed directly to the system +diff(1) command installed in PATH. + +'status':: + +Like diff, but this only prints the filenames that will be tracked +for resolutions. + +'gc':: + +This command is used to prune records of conflicted merge that +occurred long time ago. + + DISCUSSION ----------
diff --git a/tutorial-2.html b/tutorial-2.html index c092d0e..c954b77 100644 --- a/tutorial-2.html +++ b/tutorial-2.html
@@ -284,6 +284,7 @@ $ git add . $ git commit -a -m "initial commit" Committing initial tree 92b8b694ffb1675e5975148e1121810081dbdffe + create mode 100644 file.txt $ echo 'hello world!' >file.txt $ git commit -a -m "add emphasis"</tt></pre> </div></div> @@ -635,7 +636,7 @@ </div> <div id="footer"> <div id="footer-text"> -Last updated 03-Oct-2006 08:41:43 UTC +Last updated 13-Dec-2006 21:32:09 UTC </div> </div> </body>
diff --git a/tutorial-2.txt b/tutorial-2.txt index 42b6e7d..6389de5 100644 --- a/tutorial-2.txt +++ b/tutorial-2.txt
@@ -23,6 +23,7 @@ $ git add . $ git commit -a -m "initial commit" Committing initial tree 92b8b694ffb1675e5975148e1121810081dbdffe + create mode 100644 file.txt $ echo 'hello world!' >file.txt $ git commit -a -m "add emphasis" ------------------------------------------------
diff --git a/tutorial.html b/tutorial.html index 77b3f79..5a7fa51 100644 --- a/tutorial.html +++ b/tutorial.html
@@ -337,13 +337,48 @@ thorough description. Tools that turn commits into email, for example, use the first line on the Subject line and the rest of the commit in the body.</p> -<p>To add a new file, first create the file, then</p> -<div class="listingblock"> +</div> +<h2>Git tracks content not files</h2> +<div class="sectionbody"> +<p>With git you have to explicitly "add" all the changed _content_ you +want to commit together. This can be done in a few different ways:</p> +<p>1) By using <em>git add <file_spec>…</em></p> +<div class="literalblock"> <div class="content"> -<pre><tt>$ git add path/to/new/file</tt></pre> +<pre><tt>This can be performed multiple times before a commit. Note that this +is not only for adding new files. Even modified files must be +added to the set of changes about to be committed. The "git status" +command gives you a summary of what is included so far for the +next commit. When done you should use the 'git commit' command to +make it real.</tt></pre> </div></div> -<p>then commit as usual. No special command is required when removing a -file; just remove it, then tell <tt>commit</tt> about the file as usual.</p> +<div class="literalblock"> +<div class="content"> +<pre><tt>Note: don't forget to 'add' a file again if you modified it after the +first 'add' and before 'commit'. Otherwise only the previous added +state of that file will be committed. This is because git tracks +content, so what you're really 'add'ing to the commit is the *content* +of the file in the state it is in when you 'add' it.</tt></pre> +</div></div> +<p>2) By using <em>git commit -a</em> directly</p> +<div class="literalblock"> +<div class="content"> +<pre><tt>This is a quick way to automatically 'add' the content from all files +that were modified since the previous commit, and perform the actual +commit without having to separately 'add' them beforehand. This will +not add content from new files i.e. files that were never added before. +Those files still have to be added explicitly before performing a +commit.</tt></pre> +</div></div> +<p>But here's a twist. If you do <em>git commit <file1> <file2> …</em> then only +the changes belonging to those explicitly specified files will be +committed, entirely bypassing the current "added" changes. Those "added" +changes will still remain available for a subsequent commit though.</p> +<p>However, for normal usage you only have to remember <em>git add</em> + <em>git commit</em> +and/or <em>git commit -a</em>.</p> +</div> +<h2>Viewing the changelog</h2> +<div class="sectionbody"> <p>At any point you can view the history of your changes using</p> <div class="listingblock"> <div class="content"> @@ -727,7 +762,7 @@ </div> <div id="footer"> <div id="footer-text"> -Last updated 29-Nov-2006 20:40:00 UTC +Last updated 13-Dec-2006 21:32:08 UTC </div> </div> </body>
diff --git a/tutorial.txt b/tutorial.txt index fe4491d..02dede3 100644 --- a/tutorial.txt +++ b/tutorial.txt
@@ -87,14 +87,48 @@ example, use the first line on the Subject line and the rest of the commit in the body. -To add a new file, first create the file, then ------------------------------------------------- -$ git add path/to/new/file ------------------------------------------------- +Git tracks content not files +---------------------------- -then commit as usual. No special command is required when removing a -file; just remove it, then tell `commit` about the file as usual. +With git you have to explicitly "add" all the changed _content_ you +want to commit together. This can be done in a few different ways: + +1) By using 'git add <file_spec>...' + + This can be performed multiple times before a commit. Note that this + is not only for adding new files. Even modified files must be + added to the set of changes about to be committed. The "git status" + command gives you a summary of what is included so far for the + next commit. When done you should use the 'git commit' command to + make it real. + + Note: don't forget to 'add' a file again if you modified it after the + first 'add' and before 'commit'. Otherwise only the previous added + state of that file will be committed. This is because git tracks + content, so what you're really 'add'ing to the commit is the *content* + of the file in the state it is in when you 'add' it. + +2) By using 'git commit -a' directly + + This is a quick way to automatically 'add' the content from all files + that were modified since the previous commit, and perform the actual + commit without having to separately 'add' them beforehand. This will + not add content from new files i.e. files that were never added before. + Those files still have to be added explicitly before performing a + commit. + +But here's a twist. If you do 'git commit <file1> <file2> ...' then only +the changes belonging to those explicitly specified files will be +committed, entirely bypassing the current "added" changes. Those "added" +changes will still remain available for a subsequent commit though. + +However, for normal usage you only have to remember 'git add' + 'git commit' +and/or 'git commit -a'. + + +Viewing the changelog +--------------------- At any point you can view the history of your changes using
